Support for Deploying Versioned Items

For Scripts, User Configs, and API Configs defined in manifest.json, the default behavior during deployment is to either create the item if it does not exist or to create a new version of the item is does exist.

However, there may be times that you want to more closely manage the versions of the Scripts, User Configs, and API Configs for you Template Application.

For these cases the Template Package supports an optional capability to deploy versions of Scripts, User Configs, and API Configs. The method is the same for all three items.

Configuring Versions

If you wish to deploy versions of an item, configure it a you normally would in the manifest, but in the package file instead of providing a single file, create a folder with the item's name and extension. Then in that folder provide each version of the script following the naming pattern "version_\<ver number>".\<extension>. You must following this naming pattern.

For example you could configure to deploy multiple versions of "Sample Script.mjs" like so:

// manifest.json{   "Template Name": "Water Treatment Operations Digital Twin",   "Template Version": "1.0.5",   "scripts": [      {         "_name": "Sample Script",         "_shortName": "samplescr",         "_description": "A sample script",         "_userType": "sample-scr"      }   ]}

// Package Zip FileWater Treatment Template.zip /||-- scripts /|   |-- Sample Script.mjs /|       |-- version_1.mjs|       |-- version_2.mjs||-- manifest.json

// version_1.mjsexport async script(input, libraries, ctx, callback) {
   // version 1 of the script
}

// version_2.mjsexport async script(input, libraries, ctx, callback) {
   // version 2 of the script
}

Deploying Versions

When the template is deployed, if the item name is found to be a folder, the deployment will treat the item as a versioned item using the versions extracted from the version file names.

version_1.mjs -> Sample Script version 1version_2.mjs -> Sample Script version 2version_3.mjs -> Sample Script version 3

During deployment is the item does not exist, the deployment will create the item using the first version file, and then continue to create later versions of the item using the remaining version files in order.

Using the example above, the deployment would create the first version of Sample Script in Twinit using the contents of version_1.mjs. It would then create a second version of Sample Script using the contents of version_2.mjs. Then a third version with version_3.mjs.

If, during deployment, the item is found to already exist, only those versions newer than the latest version in Twinit will be created.

Using the example above, if we already had Sample Script v1 when we ran our deployment, v1 of Sample Script would be skipped and a new v2 of Sample Script would be created with the contents of version_2.mjs. Then a third version with version_3.mjs.

Be Careful

Be careful managing your versions.

If you only provide:

version_8.mjsversion_9.mjsversion_10.mjs

In cases where the item does not yet exist, your version 8, 9, and 10 contents will end up being deployed as versions 1, 2, and 3 of your scripts in Twinit.

Or if you provide version files that skip versions like:

version_1.mjsversion_2.mjsversion_5.mjs

You could get version_5.mjs deployed as versions 3, 4, and 5 in Twinit.

The versioning capability is powerful, but with great power comes great responsibility.